DocuSign Director
The DocuSign® Director module allows you to send FormFusion output as a PDF to DocuSign. DocuSign provides visibility into which users have opened a document, and allows you to request their signature on the document, based on a template that you configure in DocuSign.
In order to use this Director, you must have a current license for FormFusion and have an account with DocuSign. If you would like more information on the DocuSign Director, please contact your Evisions account representative.
Using a DocuSign Template Created in an Earlier Release
If you already have DocuSign templates in FormFusion 3.8 or 3.9, note the following:
- When you import a FormFusion template that was generated in an earlier release, the recipients list is not automatically populated. Select Refresh Recipients to update the list to the currently configured recipients.
- The email address from the To field will automatically populate the Name field in the template for 3.10. You should change the email address in the Name field to a valid name, since the text in the Name field is used as the DocuSign signature.
- The recipient from the previous release (that is, the email address shown in the To field) is automatically marked as a required signer in 3.10.
DocuSign Template Guidelines
The DocuSign template should be created based on a sample output file from FormFusion. You can use the Test Print Template feature to generate this sample, and then upload it into DocuSign to design the template.
The template you create should have an equal or lesser number of pages than the document coming over from FormFusion. If all of your signatures are on the same page, a 1-page template is ideal. You can remove unnecessary pages when editing the template in DocuSign. Using the "AutoPlace" function to base the signature location on text found in the template will tell DocuSign which page of the document should contain the signature.
FormFusion uses the template configured in DocuSign to build the list of recipients. Within DocuSign, you specify the roles and role types for the document. When creating a DocuSign template for use with FormFusion, you can include any number of recipients and use any available role types. When you display the template in FormFusion (via the FormFusion DocuSign Director) you will be able to enter the email and name for recipients with the following two role types:
- Needs to Sign
- Needs to View
When you configure the "Needs to Sign" and "Needs to View" recipients (in DocuSign), leave the Name and Email fields blank if you intend for them to be filled in via FormFusion. These fields will be populated when the FormFusion output is configured in the DocuSign Director before the document is sent.
Specifying Recipients in both the DocuSign Template and the FormFusion Director
You can specify recipients in the DocuSign template and also leave some recipient fields blank so that they are populated by FormFusion. Keep in mind:
- Recipients configured and specified in DocuSign can use any available role type (including "Needs to Sign" and "Needs to View). They will be displayed in the FormFusion Director, but will be grayed out and are not editable.
- Recipients to be specified in FormFusion can use the "Needs to Sign" or "Needs to View" role type.
Note that when you use a combination of recipients from both DocuSign and FormFusion, you must leave the name and email for at least one recipient blank for FormFusion. If there are no fields to be configured in FormFusion, the FormFusion Director will not process the document.
Once the template and role(s) are created in DocuSign (and you have entered your DocuSign credentials in FormFusion), use the Refresh Recipients button in the FormFusion DocuSign Director to update the list.
Configuring the FormFusion DocuSign Director
The DocuSign Director screen contains three main sections:
- The Execute this Director section is common to all directors.
- The DocuSign Authentication section displays the currently selected type of authentication: OAuth or Username/Password, and the account name, once the connection is working. Select the Configure button to change the authentication method and the settings used for it.
- The Details section is where you configure the output.
DocuSign Authentication Settings
The DocuSign Authentication section of the DocuSign Director screen provides options for configuring the authentication method. When configured properly, authentication allows FormFusion to access the DocuSign account.
Before you can configure the authentication settings, you must establish your DocuSign account and decide how you want FormFusion to provide credentials to DocuSign for authentication and authorization.
- Use OAuth whenever possible. It is the most secure option, and is recommended by DocuSign. FormFusion uses the Authorization Code Grant OAuth method.
If your account is inactive for approximately a month, your OAuth authorization expires. You can manually re-authenticate, or allow FormFusion to refresh the authentication on a scheduled basis. - Use the Username and Password method if the OAuth method of authorization cannot be implemented.
DocuSign Configuration for OAuth Authentication
When you select the Configure button, a DocuSign Configuration dialog displays. Select the OAuth authentication type.
For information on selecting an Environment, see Selecting an Environment (Sandbox or Production).
Obtain the Integration Key, Secret Key, and Port information from DocuSign after you add FormFusion as an approved app in your DocuSign account.
- To add FormFusion to DocuSign, in the DocuSign Admin area, go to API and Keys at the bottom of the left menu, then select Add App/Integration Key. Enter a name for the app (i.e., "FormFusion").
Be sure to obtain the following information for the app so that you can enter it on the FormFusion configuration screen.
- Integration key - After you add FormFusion as an App in DocuSign, the Integration Key is displayed. Click on the Integration Key, then use the Copy to Clipboard button to copy the entire key. Paste the key into the corresponding field in FormFusion.
Note: Make sure you copy the app's Integration Key, not the API Account ID above it.
- Continue on the same DocuSign screen to obtain the Secret key and Port information.
- Secret key - The Secret key is a type of password used with OAuth authentication. In the Authentication section of the DocuSign screen, select the Authorization Code Grant option, then select the Add Secret Key button. Copy the secret key. (Note that all but the last few characters in the secret key will be obscured the next time the key is displayed in DocuSign, after you save your changes.)
- Refresh after - The number of days between automatic refresh attempts. If you don't run the FormFusion template regularly (more frequently than about once a month), FormFusion will attempt to refresh the authorization token during FormFusion mapplet startup.
- Port - The port used for communication between DocuSign and FormFusion. On the DocuSign Add App page, enter the Redirect URI,
http://localhost:, immediately followed by an open port number. (For example, http://localhost:8081.) The port number entered on the FormFusion dialog must match the port number entered on the DocuSign account page for the Redirect URI (8081 in this example).
DocuSign Configuration for Username and Password Authentication
When you select the Configure button, a DocuSign Configuration dialog displays. Select the Username/Password authentication type.
For information on selecting an Environment, see Selecting an Environment (Sandbox or Production).
Select the Username/Password method of authentication, and then enter the username and password:
- Username - The email address associated with your DocuSign account.
- Password - The password associated with your DocuSign account.
Obtain the Integration Key from DocuSign after you add FormFusion as an approved app in your DocuSign account.
- To add FormFusion to DocuSign, in the DocuSign Admin area, go to API and Keys at the bottom of the left menu, then select Add App/Integration Key. Enter a name for the app (i.e., "FormFusion").
Be sure to obtain the following information for the app so that you can enter it on the FormFusion configuration screen.
- Integration key - After you add FormFusion as an App in DocuSign, the Integration Key is displayed. Copy and paste the entire key into the corresponding field in FormFusion. You do not need to change any other API configuration settings in DocuSign.
Note: Make sure you copy the app's Integration Key, not the API Account ID above it.
- Account ID - The account number of your DocuSign account. Note: If your user has access to multiple accounts in DocuSign, this account must be set as the default, since FormFusion will only look at the default account.
Selecting an Environment (Sandbox or Production)
As you develop your FormFusion director for DocuSign, you may want to test your configuration in an environment separated from your production environment. You can use the Sandbox environment for this purpose.
The URLs for the production and sandbox environments are pre-populated for you.
- If you are using OAuth authentication, the URL is the OAuth URL.
- If you are using a username and password for authentication, the URL is the base URL.
You can enter a different URL, if you wish.
- A custom URL is always shown as the sandbox environment.
- If using a custom URL, the environment will default to the sandbox environment.
- If you switch between the sandbox and production environments, the manually-entered URL is no longer available and is replaced by the default sandbox URL.
If you previously added a DocuSign base URL registry key to the MAPS server, FormFusion will use the registry key under the following circumstances:
- A director is opened for the first time after upgrading from FormFusion version 3.8 to version 3.9 or 3.10.
- A new DocuSign Director is created.
If the URL is populated from the registry key, the Environment dropdown will be set to Sandbox.
Details Section: Output Settings
Before you can configure the output settings in FormFusion, you must configure the template in DocuSign. See DocuSign Template Guidelines for details.
Refresh Recipients
Within FormFusion, it is good practice to use the Refresh Recipients button regularly to ensure that you are loading the latest recipient information from DocuSign. When you do this, FormFusion retrieves the latest information configured for the template.
Note that doing this clears any information already entered manually from FormFusion.
Once the template is created in DocuSign (and you have entered your DocuSign credentials into FormFusion), use the Refresh Templates button to update the list of templates. Select the template you want to use from the drop down. Then use the Details section of the FormFusion screen to configure how the output is processed.
Template
Select the name of the template that you configured in DocuSign.
Recipients Section
The Recipients section lists all of the recipients who will receive the document once it is processed. Recipients shown in gray are configured in DocuSign and cannot be edited in FormFusion. Select Refresh Recipients to get the most recent data from the DocuSign template.
The following fields are included in this area:
- Role and Role Type - Displays the role configured in the DocuSign template for each recipient and the associated role type. FormFusion supports the Needs to Sign (default) and Needs to View role types. The other types cannot be configured within the FormFusion DocuSign Director. (These recipients will still receive the document as configured in the DocuSign template.)
- Name and Email - Enter a name and email address for each recipient that does not already have the information provided by the DocuSign template. The edit boxes can contain static values (test@evisions.com), or use variables defined previously in MapForm or CaptureForm, using the colon variable notation. For example, a SQL statement can be created that retrieves the email address of the recipient and stores it into a variable named signer_email. To insert this variable, type :signer_email.
- Required - Select the check box to make the recipient a required recipient. The check box is checked by default.
- If the Required check box is unchecked, you must fill in the Name and Email fields in order for the document to be sent to that recipient. If one or both fields are missing, FormFusion will not send the document to that recipient.
- If the Name and/or Email fields are left blank while the Required check box remains checked, a message displays reminding you to complete the information.
Refresh Recipients - Select to refresh the information from DocuSign relating to recipients. Note that this will clear any fields manually entered within FormFusion. Always refresh if you believe that the DocuSign template may have changed, or if you are importing a template from a previous version of FormFusion and the list of recipients is missing.
Subject
Optional. The subject line of the email that will be sent to recipients. The subject can be typed in manually or use a combination of manual text and FormFusion variables.
Key
Optional. Defines a string that an imaging system will search for within the PDF output. This key definition should exactly match the key configured in imaging system. Please refer to your imaging system's documentation regarding configuration of the key. The key field can include variables from MapForm or CaptureForm, using a colon preceding the variable name. FormFusion will place the generated key in "invisible" white text on every page of the output.
Filename
Optional. The name of the PDF file to be sent to the recipient. You may use a variable as part of the filename. The .pdf file extension is not required. If this field is left blank, the filename will default to doc.pdf.
Break pages on
Optional. Specifies how the DocuSign Director parses the output file into individual files. A MapForm or CaptureForm variable should be entered, with a colon preceding the variable name. In the figure above, the PONumber variable was created in either MapForm or CaptureForm. The value used for this variable must be present on each page of the output file and positioned consistently from page to page. Each time the PONumber variable changes, a new PDF will be created.
Binary Format
The output format of the document. This is always set to PDF for DocuSign. Use the Options button to configure PDF details such as document information, encryption, and file compression.
Password Encryption
DocuSign does not support password protected PDFs. The User Password field found under the Encryption section of the PDF Options window should be left blank.
Troubleshooting
- Use the Refresh Recipients button to update the list of recipients from DocuSign.
- Ensure that the Name and Email fields for the recipients that are to be configured in FormFusion are blank in DocuSign if you want them to be managed via FormFusion.
- Ensure that the role type for each recipient is set to either "Needs to Sign" or "Needs to View" for any recipient to be configured in FormFusion.
- You must save your changes in DocuSign before FormFusion can see them.
- Refer to the DocuSign documentation for information on setting up roles and using role types within the DocuSign template.